home *** CD-ROM | disk | FTP | other *** search
Text File | 1991-03-03 | 16.2 KB | 334 lines | [TEXT/MSWD] |
- ResHelper - Version 0.80
-
-
- A Quick Word from the Author:
- ============================
- I've been working on ResHelper off and on for nearly a year as of March,
- 1991. I wrote this program to address some complaints I had about other
- resource building programs and learn more about the internals of the
- Mac. Early on, I decided to solicit suggestions from readers of the
- INFO-MAC digest available on the BITNET and INTERNET computer networks
- to see if there were other features that might prove useful to other
- users. Several readers (maybe 15) responded and some of their
- suggestions have been incorporated into this program.
-
- At this point, I think I've met most of the goals I set for myself in
- writing this. Since the program seems to be fairly well behaved, I've
- decided to try my luck at shareware and make it available to INFO-MAC
- readers. Because I graduated from Washington University in May of 1990,
- I no longer have direct access to INFO-MAC. However, I still have
- connections! Eric Oberle, Manager - Computer Consulting at Washington
- University not only tried out early versions and provided some helpful
- suggestions, but has graciously volunteered to post the program to INFO-
- MAC and accept comments from users via electronic mail and forward them
- to me. Eric's e-mail address is:
-
- Eric Oberle <C09615EO@WUVMD.BITNET>
-
- Thank you Eric! You can also send comments directly to me at the
- following address:
-
- Michael Hanrahan
- 1142 West College - Apt K
- Liberty, MO 64068
- USA
-
- Now is your chance to actively participate in the development of
- something designed to help YOU! I cannot promise this program will be
- supported with an 800 number and quarterly newsletters but then you
- aren't expected to pay for that either. Version 0.80 is being offered
- as shareware for a fee of $30 (US funds). If you send in your shareware
- fee to me at the above address, I will send you a copy of the latest
- version on a new diskette.
-
- NOTE: This release of ResHelper has a 60-day "timer" within it which
- will disable all commands but Help and Quit 60 days after you
- first run the program. This "timer" is not intended to punish
- users who don't send in shareware fees but rather to prevent
- obsolete versions of the program from persisting in the
- electronic ether indefinitely. Users who send in their shareware
- fee will be provided a version which does not include the timer.
-
-
- (now the real help file!)
-
- Introduction
- ============
- One of the most tedious aspects of Macintosh software development is the
- creation of resources used within the program. Despite the Macintosh's
- status as the most elegant graphics-based computer on the market, some
- resource builders for Macintosh developers require resource "source
- code" to be written and "compiled" into the final form or require the
- same type of information to be specified via dialogs rather than point-
- click-drag techniques.
-
- ResHelper was written to yield the following capabilities:
-
- 1) Allow programmers to specify Finder Bundles in a way that the
- user sees them, without worrying about local resource IDs,
- global resource IDs, maps between the BNDL and FREFs, etc.
- 2) Allow dialogs to be edited using standard draw program methods.
- Select and move multiple items (ResEdit can't do this). Change
- control names/edit text without having to open a separate dialog.
- Support clipboard functions while editing dialogs. Allow all
- item numbers to be seen and modified in one dialog.
- 3) Allow menus to be created and "test-driven" within the program
- to verify the placement of separator bars, command key
- equivalents, etc.
- 4) Perform the above functions and others without costing the
- developer an arm and a leg.
-
- ResHelper has been written with safety in mind as well. When you edit
- resources in a file, ResHelper actually makes a copy of the file and
- applies your changes to the copy. The original input file remains
- untouched while you edit resources until you issue a Save command. This
- disk-based approach may be a tad slow for users without hard drives but
- it guarantees that your input file will NEVER be corrupted by the
- program and it allows the program to run in a fairly small 350k
- partition under MultiFinder.
-
-
- History
- =======
- ResHelper was written using THINK's Pascal Version 3.0 on a Macintosh SE
- (for the first four months) and IIci (the remainder). It has been
- thoroughly tested on System 6.0.5 on the IIci and will run in as little
- as 350k under MultiFinder. By the way, a big hats off to the people at
- Symantec. THINK Pascal is the only program I've used for EXTENDED (and
- I mean EXTENDED!) periods of time without having the phrase "I really
- wish they had thought of _____ when they wrote this" pop into my head A
- very well thought out product, to say the least...
-
-
- Behind the Scenes
- =================
- After you select a file for editing, ResHelper creates a copy of the
- input file and places the copy, named $$$TEMP RESOURCE$$$ in your System
- folder. The program also adds an extra resource (named 'fnam') to the
- copy which contains the name of the input file name and its Finder
- information. After making any desired changes and issuing a Save
- command, ResHelper deletes the old version of your input file, then
- copies the temp file back to the original's folder (or a different
- folder and name if you did a Save As...). It then removes the 'fnam'
- resource from the newly saved file.
-
- Why is the 'fnam' resource added and removed? If ResHelper ever
- terminates abnormally (or something else in your Mac hangs), the temp
- file with that 'fnam' resource will be left in your System folder. The
- next time ResHelper is launched, it will detect the presence of that old
- work file and use the filename within the 'fnam' resource to remind you
- of the old session and ask if you wish to continue. Since the program
- immediately writes out all resources to that temp file as they are
- created/changed, you should never lose more work than the changes to a
- single resource. EVER.
-
-
- Using the Resource Editors
- ==========================
- The use of most of the resource editors in ResHelper is fairly obvious.
- However, the Bundle and Dialog editors deserve some special coverage
- since they combine the process of editing several different resources
- into a single integrated environment. Detailed descriptions of these
- editors are given below.
-
- Editing Your Application's Finder Information
- ---------------------------------------------
- The Finder uses three pre-defined resources types (BNDL, FREF, and SIZE)
- and a user-defined resource (referred to as a signature) to control the
- application's appearance in the Finder and its use of memory when
- launched under MultiFinder. A quick description of these resources is
- given below.
-
- Type Purpose
- ---- -------------------------------------------------
- BNDL Provides a summary to the Finder of how many unique file
- types your program uses. It contains a map of all the
- FREF resources which define those types. It also contains
- the (hopefully) unique signature of your application.
- FREF Provide a one-to-one map between a four-character file type
- and an ICN# resource to display for files of that file type.
- There is one FREF resource for each file type your program.
- creates.
- SIZE Used by the Finder to provide a memory partition if your
- program is run under MultiFinder. It also contains a set
- of flags which you use to tell the System how MultiFinder
- "smart" your application is. Always saved with id = -1.
- sign If your application's signature was 'sign', you would have
- a resource of type 'sign' which contains a string which will
- be displayed in the Version field when the user chooses the
- Get Info command in Finder's File menu on your final
- application.
-
- Sounds simple, huh? In fact, the process of creating all these
- resources is normally rather confusing and tedious. ResHelper provides
- three dialogs which greatly simplify this process.
-
- The Size Dialog
- ---------------
- The suggested memory partition field should contain the amount of memory
- (in kilobytes) in which your program operates most efficiently. The
- minimum should specify the smallest amount of memory in which your
- program can operate without encountering memory allocation problems.
-
- The flags deserve some special explanation. Some key points are
- summarized in the table below. (By the way, I have no idea what the
- Save Screen flag's function is.)
-
- 32 bit clean
-
- You probably shouldn't check this unless you've successfully
- tested your program under A/UX.
-
- getFrontClicks
-
- When your program has been placed in the background under
- MultiFinder and the user clicks on a window to bring your program
- back to the foreground, MultiFinder will normally NOT pass your
- program the mouse-down event which brought it back to the front (you
- probably don't need to see the event anyway). If you DO wish to
- receive this event, check this box.
-
- acceptSuspendResumeEvents
-
- Set this flag if your event handling routine includes support for
- processing suspend/resume events. If you don't check this option,
- MF will generate extra "bogus" events designed to trick your program
- into performing any clipboard housekeeping. For this to have any
- effect, the MultiFinder aware flag should also be set.
-
- MultiFinder aware
-
- Setting this flag tells MultiFinder that it won't need to generate
- activate/deactivate events along with the resume/suspend
-
- canBackground
-
- MultiFinder provides "time slices" to background applications by
- passing null events to them. If your program doesn't do anything
- for null events, don't set this flag.
-
- onlyBackground
-
- If your program doesn't have a user interface (no menus, dialogs,
- etc.) and cannot run in the foreground, set this flag.
-
- getChildDiedEvents
-
- If your program launches other applications and you want to know if
- they terminated abnormally, set this flag.
-
-
- The Bundle Dialog
- -----------------
- The Bundle dialog allows you to specify your application's four-
- character signature, its Get Info string ("signature string"), and lists
- all the file types (FREFs) you've defined with their associated ICN#.
- If you need to create a new FREF, click on the New FREF button. A
- second dialog will appear which displays all defined ICN#s and provides
- a field for your new file type. Type in your new file type, select an
- ICN# then click on Select. Cancel returns you to the main Bundle
- dialog. Clicking on Save in the Bundle dialog saves all of the various
- resources and construct the maps between your FREFs and ICN#s. (If this
- sounds complicated, you should try it the old way once just for fun!)
-
-
- Editing Dialogs
- ---------------
- Editing dialogs is also much easier using ResHelper. Choosing the
- Dialogs command in the Resource menu displays a list of all defined
- DLOGs. Double-clicking on an item will display that dialog as the end
- user will see it. Once a dialog is displayed you can perform all of the
- following functions:
-
- • Create an item by clicking on the desired tool in the palette then
- clicking where you want it in the dialog window.
- • Reposition an item by clicking on it and dragging it to the proper
- position.
- • Resize an item by dragging its bottom right selection handle. When
- resizing text boxes, the height will automatically be rounded to
- the nearest integral multiple of the Chicago font size.
- • Select multiple items by holding down Shift while clicking on the
- items. You can also drag a rectangle around items to select them
- (as you do in the Finder).
- • Hold down Shift while dragging to limit movement to the horizontal
- or vertical direction.
- • Change a control's title or the text in a statText or editText
- item by double clicking on that item to select the text, type the
- new title, then press Esc or click outside the item's rectangle to
- finish editing.
- • Resize the dialog window by dragging in the lower right corner.
- • Move the dialog window around the screen by dragging its title bar
- (if it has one) or by clicking in the first four rows of pixels at
- the top of the window and dragging.
- • Add PICTs or ICONs by clicking on the appropriate tool, click in
- the window where you wish to place it, then select the desired
- PICT/ICON from a list of defined resources. Poof! It's added.
- You can edit the ICONs in the dialog by double clicking on them.
-
- The Windows Options... dialog allows you to specify the type of window
- for the dialog and indicate whether the dialog window should be
- initially hidden (useful if you wish to center the window before showing
- it to the user) or have a close box (for document-type windows). You
- can change window types even if you've already added items to the
- dialog.
-
- The Set Item Numbers... dialog lists all defined dialog items in
- numerical order. You can renumber an item by dragging it on top of the
- item it should follow in the list. Clicking on Finish returns you to
- your dialog for more editing.
-
- When you save a new dialog, you will be prompted for the dialog's title
- and the resource IDs of the DLOG and DITL resources (normally you'll
- want to keep these the same). The title will be used to provide a name
- to the resource which helps identify them later. You can change this
- information later by choosing the Save As.. command in the Dialog menu
- instead of Save. If you create a dialog window which is larger than the
- 9-inch screen on the compact Macintosh models or you positioned the
- window so it is not entirely visible on the classic screens, you'll be
- warned of this fact at the time you save the dialog.
-
- MF Strings
- ----------
- If your program uses non-standard command names for "Open..." and "Quit"
- or places them in a menu called something other than "File", your
- program will not support MultiFinder's ability to open documents from
- the Finder while your program is already loaded or quit when the user
- selects Restart/Shutdown. If you wish to support these features, you
- need to tell MultiFinder which menu contains these commands and the
- exact name of the commands. The MF Strings dialog allows you to specify
- the strings needed to pass this information to MultiFinder.
-
- After filling in the fields in the dialog, ResHelper will save the
- strings out as type 'mstr' with ids 100-103. When your program is
- running, if MultiFinder can't find the Open or Quit command in their
- normal menu, it will look for these resources in its attempt to find
- them.
-
-
- Unfinished Business
- ===================
- I'm hoping that many users will provide some feedback about
- features they like or found lacking in the program. However, I'm sure I
- can guess what some of them are. The following is a list of the
- features I'm still trying to implement in the program.
-
- 1) I have the routines to draw lines and boxes and outline the default
- button in a dialog working but haven't figured out a viable way to
- save them. Actually, saving them as PICTs is easy but when a
- dialog is opened for editing and read from the DITL on disk, I'll
- need to be able to determine if the PICT is something I created or
- a random PICT representing a digitized Van Gogh or something
- meaningless to ResHelper. (Sounds like a job for picComments!)
- 2) A better algorithm for automatically building an icon mask for
- ICN#s is needed.
- 3) Support for running in a shared environment. I hope to dynamically
- assign temp file filenames yet continue to allow sessions to be
- restarted. This will require checking along the lines of "1) does
- a temp file exist?" and "2) does it belong to THIS user?"
- 4) Support for editing color icons. I don't know of any program that
- edits cicn's in a Paint-like environment so I imagine this could be
- VERY difficult to implement.
-
- Even without these features, I think/hope most programmers will find
- ResHelper very useful in developing their own software.
-